The cross-env npm package is a cross-platform solution for setting and using environment variables in scripts. It works well for both Windows and UNIX-based systems (like Linux and macOS), making it easier to write scripts that work across different environments without modification.
Setting environment variables
This feature allows you to set environment variables in your npm scripts. The code sample sets the NODE_ENV variable to 'production' before executing 'node app.js'.
cross-env NODE_ENV=production node app.jsSetting multiple environment variables
With cross-env, you can set multiple environment variables at once. The code sample sets both NODE_ENV and API_KEY before running 'node app.js'.
cross-env NODE_ENV=production API_KEY=12345 node app.jsInline environment variable setting
You can use cross-env to set environment variables inline with your script execution. The code sample sets the GREETING variable and immediately runs a node command that logs the value of GREETING.
cross-env GREETING='Hello, World!' node -e "console.log(process.env.GREETING)"env-cmd is a similar package that allows you to specify a file containing environment variable definitions. It's a bit different from cross-env because it doesn't set variables inline but rather reads them from a file.
dotenv is another package that loads environment variables from a .env file into process.env. It's commonly used for development purposes and differs from cross-env in that it's not intended for setting variables directly in scripts.
dotenv-expand extends dotenv by allowing you to have environment variables that reference other environment variables within your .env file. It's more about expanding variables rather than setting them in scripts like cross-env.
Run scripts that set and use environment variables across platforms
🚨 NOTICE: cross-env still works well, but is in maintenance mode. No new features will be added, only serious and common-case bugs will be fixed, and it will only be kept up-to-date with Node.js over time. Learn more
Most Windows command prompts will choke when you set environment variables with
NODE_ENV=production like that. (The exception is Bash on Windows,
which uses native Bash.) Similarly, there's a difference in how windows and
POSIX commands utilize environment variables. With POSIX, you use: $ENV_VAR
and on windows you use %ENV_VAR%.
cross-env makes it so you can have a single command without worrying about
setting or using the environment variable properly for the platform. Just set it
like you would if it's running on a POSIX system, and cross-env will take care
of setting it properly.
cross-env vs cross-env-shellThis module is distributed via npm which is bundled with node and
should be installed as one of your project's devDependencies:
npm install --save-dev cross-env
WARNING! Make sure that when you're installing packages that you spell things correctly to avoid mistakenly installing malware
NOTE : Version 7 of cross-env only supports Node.js 10 and higher, to use it on Node.js 8 or lower install version 6
npm install --save-dev cross-env@6
I use this in my npm scripts:
{
"scripts": {
"build": "cross-env NODE_ENV=production webpack --config build/webpack.config.js"
}
}
Ultimately, the command that is executed (using cross-spawn)
is:
webpack --config build/webpack.config.js
The NODE_ENV environment variable will be set by cross-env
You can set multiple environment variables at a time:
{
"scripts": {
"build": "cross-env FIRST_ENV=one SECOND_ENV=two node ./my-program"
}
}
You can also split a command into several ones, or separate the environment variables declaration from the actual command execution. You can do it this way:
{
"scripts": {
"parentScript": "cross-env GREET=\"Joe\" npm run childScript",
"childScript": "cross-env-shell \"echo Hello $GREET\""
}
}
Where childScript holds the actual command to execute and parentScript sets
the environment variables to use. Then instead of run the childScript you run
the parent. This is quite useful for launching the same command with different
env variables or when the environment variables are too long to have everything
in one line. It also means that you can use $GREET env var syntax even on
Windows which would usually require it to be %GREET%.
If you precede a dollar sign with an odd number of backslashes the expression
statement will not be replaced. Note that this means backslashes after the JSON
string escaping took place. "FOO=\\$BAR" will not be replaced.
"FOO=\\\\$BAR" will be replaced though.
Lastly, if you want to pass a JSON string (e.g., when using ts-loader), you can do as follows:
{
"scripts": {
"test": "cross-env TS_NODE_COMPILER_OPTIONS={\\\"module\\\":\\\"commonjs\\\"} node some_file.test.ts"
}
}
Pay special attention to the triple backslash (\\\) before the
double quotes (") and the absence of single quotes ('). Both of
these conditions have to be met in order to work both on Windows and UNIX.
cross-env vs cross-env-shellThe cross-env module exposes two bins: cross-env and cross-env-shell. The
first one executes commands using cross-spawn, while the second
one uses the shell option from Node's spawn.
The main use case for cross-env-shell is when you need an environment variable
to be set across an entire inline shell script, rather than just one command.
For example, if you want to have the environment variable apply to several
commands in series then you will need to wrap those in quotes and use
cross-env-shell instead of cross-env.
{
"scripts": {
"greet": "cross-env-shell GREETING=Hi NAME=Joe \"echo $GREETING && echo $NAME\""
}
}
The rule of thumb is: if you want to pass to cross-env a command that contains
special shell characters that you want interpreted, then use
cross-env-shell. Otherwise stick to cross-env.
On Windows you need to use cross-env-shell, if you want to handle
signal events
inside of your program. A common case for that is when you want to capture a
SIGINT event invoked by pressing Ctrl + C on the command-line interface.
Please note that npm uses cmd by default and that doesn't support command
substitution, so if you want to leverage that, then you need to update your
.npmrc to set the script-shell to powershell.
Learn more here.
I originally created this to solve a problem I was having with my npm scripts in angular-formly. This made contributing to the project much easier for Windows users.
env-cmd - Reads environment
variables from a file instead@naholyr/cross-env -
cross-env with support for setting default valuesLooking to contribute? Look for the Good First Issue label.
Please file an issue for bugs, missing documentation, or unexpected behavior.
This project is in maintenance mode and no new feature requests will be considered.
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Note: this was added late into the project. If you've contributed to this project in any way, please make a pull request to add yourself to the list by following the instructions in the
CONTRIBUTING.md
MIT
FAQs
Run scripts that set and use environment variables across platforms
The npm package cross-env receives a total of 4,394,140 weekly downloads. As such, cross-env popularity was classified as popular.
We found that cross-env demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new OpenSSF report uncovers critical gaps in secure software training, with 75% of new developers unfamiliar with secure practices, highlighting urgent educational needs.
Security News
The 2023 Python Developers Survey reveals key trends in packaging, web frameworks, and developer demographics, highlighting a shift toward innovative tools as the Python community diversifies and grows among less experienced developers.
Security News
GitHub is combatting a new spam campaign that exploits issues with links to malicious downloads, highlighting the need for better moderation tools to protect open-source maintainers' time and security.
